<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.gradient &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" >
    <link rel="index" title="Index" href="../../genindex.html" >
    <link rel="search" title="Search" href="../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../index.html" >
    <link rel="up" title="Mathematical functions" href="../routines.math.html" >
    <link rel="next" title="numpy.cross" href="numpy.cross.html" >
    <link rel="prev" title="numpy.ediff1d" href="numpy.ediff1d.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../index.html">
      <img border=0 alt="NumPy" src="../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../routines.html" >Routines</a></li>
          <li class="active"><a href="../routines.math.html" accesskey="U">Mathematical functions</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.cross.html" title="numpy.cross"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.ediff1d.html" title="numpy.ediff1d"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.ediff1d.html"
                        title="previous chapter">numpy.ediff1d</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.cross.html"
                        title="next chapter">numpy.cross</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-gradient">
<h1>numpy.gradient<a class="headerlink" href="#numpy-gradient" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="numpy.gradient">
<code class="sig-prename descclassname">numpy.</code><code class="sig-name descname">gradient</code><span class="sig-paren">(</span><em class="sig-param">f</em>, <em class="sig-param">*varargs</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/numpy/numpy/blob/v1.18.1/numpy/lib/function_base.py#L786-L1134"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#numpy.gradient" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the gradient of an N-dimensional array.</p>
<p>The gradient is computed using second order accurate central differences
in the interior points and either first or second order accurate one-sides
(forward or backwards) differences at the boundaries.
The returned gradient hence has the same shape as the input array.</p>
<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl>
<dt><strong>f</strong><span class="classifier">array_like</span></dt><dd><p>An N-dimensional array containing samples of a scalar function.</p>
</dd>
<dt><strong>varargs</strong><span class="classifier">list of scalar or array, optional</span></dt><dd><p>Spacing between f values. Default unitary spacing for all dimensions.
Spacing can be specified using:</p>
<ol class="arabic simple">
<li><p>single scalar to specify a sample distance for all dimensions.</p></li>
<li><p>N scalars to specify a constant sample distance for each dimension.
i.e. <em class="xref py py-obj">dx</em>, <em class="xref py py-obj">dy</em>, <em class="xref py py-obj">dz</em>, …</p></li>
<li><p>N arrays to specify the coordinates of the values along each
dimension of F. The length of the array must match the size of
the corresponding dimension</p></li>
<li><p>Any combination of N scalars/arrays with the meaning of 2. and 3.</p></li>
</ol>
<p>If <em class="xref py py-obj">axis</em> is given, the number of varargs must equal the number of axes.
Default: 1.</p>
</dd>
<dt><strong>edge_order</strong><span class="classifier">{1, 2}, optional</span></dt><dd><p>Gradient is calculated using N-th order accurate differences
at the boundaries. Default: 1.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.9.1.</span></p>
</div>
</dd>
<dt><strong>axis</strong><span class="classifier">None or int or tuple of ints, optional</span></dt><dd><p>Gradient is calculated only along the given axis or axes
The default (axis = None) is to calculate the gradient for all the axes
of the input array. axis may be negative, in which case it counts from
the last to the first axis.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.11.0.</span></p>
</div>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>gradient</strong><span class="classifier">ndarray or list of ndarray</span></dt><dd><p>A set of ndarrays (or a single ndarray if there is only one dimension)
corresponding to the derivatives of f with respect to each dimension.
Each derivative has the same shape as f.</p>
</dd>
</dl>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>Assuming that <img class="math" src="../../_images/math/c984d9061d8c73b1fa0a81e57161351be89127ff.svg" alt="f\in C^{3}"/> (i.e., <img class="math" src="../../_images/math/5b7752c757e0b691a80ab8227eadb8a8389dc58a.svg" alt="f"/> has at least 3 continuous
derivatives) and let <img class="math" src="../../_images/math/96133e1993b915c8ffff9c2624de0aab0e3bb70d.svg" alt="h_{*}"/> be a non-homogeneous stepsize, we
minimize the “consistency error” <img class="math" src="../../_images/math/f4145f60e2794e659a59aa47b833df5729dbb8ab.svg" alt="\eta_{i}"/> between the true gradient
and its estimate from a linear combination of the neighboring grid-points:</p>
<div class="math">
<p><img src="../../_images/math/92ff9de81a494fc27fe92ada7ab13d5e58721c6d.svg" alt="\eta_{i} = f_{i}^{\left(1\right)} -
            \left[ \alpha f\left(x_{i}\right) +
                    \beta f\left(x_{i} + h_{d}\right) +
                    \gamma f\left(x_{i}-h_{s}\right)
            \right]"/></p>
</div><p>By substituting <img class="math" src="../../_images/math/973237f21e206ee01e9d0f3f75a0c39d72e6d6ec.svg" alt="f(x_{i} + h_{d})"/> and <img class="math" src="../../_images/math/62962db691712464cfc4e66aad32e876155dd5f9.svg" alt="f(x_{i} - h_{s})"/>
with their Taylor series expansion, this translates into solving
the following the linear system:</p>
<div class="math">
<p><img src="../../_images/math/ebad75f65be0603d33346af3c0aa7ac8e7fe7624.svg" alt="\left\{
    \begin{array}{r}
        \alpha+\beta+\gamma=0 \\
        \beta h_{d}-\gamma h_{s}=1 \\
        \beta h_{d}^{2}+\gamma h_{s}^{2}=0
    \end{array}
\right."/></p>
</div><p>The resulting approximation of <img class="math" src="../../_images/math/7e83e1adc970db4cfc23ff32d2bded2d33934397.svg" alt="f_{i}^{(1)}"/> is the following:</p>
<div class="math">
<p><img src="../../_images/math/c72b9a79bd07a946164f02b0b6d462c415f03a3e.svg" alt="\hat f_{i}^{(1)} =
    \frac{
        h_{s}^{2}f\left(x_{i} + h_{d}\right)
        + \left(h_{d}^{2} - h_{s}^{2}\right)f\left(x_{i}\right)
        - h_{d}^{2}f\left(x_{i}-h_{s}\right)}
        { h_{s}h_{d}\left(h_{d} + h_{s}\right)}
    + \mathcal{O}\left(\frac{h_{d}h_{s}^{2}
                        + h_{s}h_{d}^{2}}{h_{d}
                        + h_{s}}\right)"/></p>
</div><p>It is worth noting that if <img class="math" src="../../_images/math/c349da7b7910fd82e0d33134cad9b33c2624b6fa.svg" alt="h_{s}=h_{d}"/>
(i.e., data are evenly spaced)
we find the standard second order approximation:</p>
<div class="math">
<p><img src="../../_images/math/53a10c44fbd2a86ebd9ceeab37c1f87a509e4f33.svg" alt="\hat f_{i}^{(1)}=
    \frac{f\left(x_{i+1}\right) - f\left(x_{i-1}\right)}{2h}
    + \mathcal{O}\left(h^{2}\right)"/></p>
</div><p>With a similar procedure the forward/backward approximations used for
boundaries can be derived.</p>
<p class="rubric">References</p>
<dl class="citation">
<dt class="label" id="ra2d2bdda2b24-1"><span class="brackets">1</span></dt>
<dd><p>Quarteroni A., Sacco R., Saleri F. (2007) Numerical Mathematics
(Texts in Applied Mathematics). New York: Springer.</p>
</dd>
<dt class="label" id="ra2d2bdda2b24-2"><span class="brackets">2</span></dt>
<dd><p>Durran D. R. (1999) Numerical Methods for Wave Equations
in Geophysical Fluid Dynamics. New York: Springer.</p>
</dd>
<dt class="label" id="ra2d2bdda2b24-3"><span class="brackets">3</span></dt>
<dd><p>Fornberg B. (1988) Generation of Finite Difference Formulas on
Arbitrarily Spaced Grids,
Mathematics of Computation 51, no. 184 : 699-706.
<a class="reference external" href="http://www.ams.org/journals/mcom/1988-51-184/S0025-5718-1988-0935077-0/S0025-5718-1988-0935077-0.pdf">PDF</a>.</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">16</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go">array([1. , 1.5, 2.5, 3.5, 4.5, 5. ])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="go">array([0.5 ,  0.75,  1.25,  1.75,  2.25,  2.5 ])</span>
</pre></div>
</div>
<p>Spacing can be also specified with an array that represents the coordinates
of the values F along the dimensions.
For instance a uniform spacing:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">size</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span>
<span class="go">array([1. ,  1.5,  2.5,  3.5,  4.5,  5. ])</span>
</pre></div>
</div>
<p>Or a non uniform one:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.</span><span class="p">,</span> <span class="mf">1.</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">,</span> <span class="mf">3.5</span><span class="p">,</span> <span class="mf">4.</span><span class="p">,</span> <span class="mf">6.</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span>
<span class="go">array([1. ,  3. ,  3.5,  6.7,  6.9,  2.5])</span>
</pre></div>
</div>
<p>For two dimensional arrays, the return will be two arrays ordered by
axis. In this example the first array stands for the gradient in
rows and the second one in columns direction:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">]],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">))</span>
<span class="go">[array([[ 2.,  2., -1.],</span>
<span class="go">       [ 2.,  2., -1.]]), array([[1. , 2.5, 4. ],</span>
<span class="go">       [1. , 1. , 1. ]])]</span>
</pre></div>
</div>
<p>In this example the spacing is also specified:
uniform for axis=0 and non uniform for axis=1</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">dx</span> <span class="o">=</span> <span class="mf">2.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span> <span class="o">=</span> <span class="p">[</span><span class="mf">1.</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">,</span> <span class="mf">3.5</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">]],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">),</span> <span class="n">dx</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
<span class="go">[array([[ 1. ,  1. , -0.5],</span>
<span class="go">       [ 1. ,  1. , -0.5]]), array([[2. , 2. , 2. ],</span>
<span class="go">       [2. , 1.7, 0.5]])]</span>
</pre></div>
</div>
<p>It is possible to specify how boundaries are treated using <em class="xref py py-obj">edge_order</em></p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">x</span><span class="o">**</span><span class="mi">2</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">edge_order</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="go">array([1.,  2.,  4.,  6.,  7.])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">edge_order</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="go">array([0., 2., 4., 6., 8.])</span>
</pre></div>
</div>
<p>The <em class="xref py py-obj">axis</em> keyword can be used to specify a subset of axes of which the
gradient is calculated</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">]],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">),</span> <span class="n">axis</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
<span class="go">array([[ 2.,  2., -1.],</span>
<span class="go">       [ 2.,  2., -1.]])</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>